package me.softwareengineer.guice.rendering.domain;

import java.util.Map;

import me.softwareengineer.guice.rendering.listener.Listener;
import me.softwareengineer.guice.rendering.listener.OnAnchorEvent;

/**
 * Represents pointer or location in a page. It allows the anchor to be the 
 * destination of a URL. The value of the {@link #getName()} is an identifier for the anchor. 
 * Identifiers are arbitrary strings but must be unique within the {@link DOM}. 
 * Another document can then make a reference explicitly to this anchor by putting 
 * the identifier after the element address. 
 * 
 *
 * <p>
 * Event: the following event is generated during {@link #render(Listener)}:
 * <ul>
 * <li>{@link OnAnchorEvent}</li>
 * </ul>
 * </p>
 * <pre>
 * Example:
 * 
 * Wiki Syntax                                 DOM Repersentation
 * -----------------------------------------------------------------
 * = this test =                               +document
 * test                                         +section
 *                                               +header 1
 *                                                +anchorElement (name='this_test')
 *                                                   +paragraph test
 *                                                -anchorElement
 *                                                -header1
 *                                               -section
 *                                              -document
 * </pre>
 * 
 * <pre>
 * This class is thread-safe and can be cached/re-used and used concurrently.
 * </pre>
 * 
 * @author yadtahir
 * @since 1.0
 * 
 */
//This class is final since we want to make it immutable as much as possible
public final class AnchorElement extends Element {
	/**
	 * The unique name for the reference/location.
	 */
	private final String name;


	/**
	 * Creates an anchor element with no properties
	 * 
	 * @param name arbitrary strings but must be unique within the {@link DOM}
	 */
	public AnchorElement(String name) {
		this.name = name;
	}

	/**
	 * Creates an anchor element with the provided properties
	 * 
	 * @param name
	 *            the unique name of the anchor
	 * @param properties
	 *            the properties of the element. For more info, check
	 *            {@link HasProperties}
	 */
	public AnchorElement(String name, Map<String, String> properties) {
		super(properties);
		this.name = name;
	}

	/**
	 * 
	 * @return the unique name for the anchor
	 * <p>
	 * This property is immutable and thread-safe
	 * </p>
	 */
	public String getName() {
			return name;
	}

	/**
	 * {@inheritDoc}
	 * <p>
	 * The following event is generated during {@link #render(Listener)}:
	 * 	<ul>
	 * 	<li>{@link OnAnchorEvent}</li>
	 * <ul>
	 * <p>
	 */
	@Override
	public void render(Listener listener) {
		OnAnchorEvent e = new OnAnchorEvent(getName(), getAllProperties());
		listener.onEvent(e);
	}



}
